<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>Configuring Crunchy</title>
<link href="tutor.css" title="Tutor Style" type="text/css" rel="stylesheet" />
<link href="tutor_bw.css" title="Black and white" type="text/css" rel="stylesheet" />

</head>
<body>
<div id="topbar">
<img alt="" src="argh.gif" class="titleimage"/>
<span class="title">Configuring Crunchy</span>
</div>
<div id="navbar">
<span class="heading">Crunchy user tutorial</span>
<a href="welcome_en.html">Begin tutorial</a>
<a href="interpreter_en.html">Interpreter</a>
<a href="editor_en.html">Editor</a>
<a href="doctest_en.html">DocTest</a>
<a href="canvas_en.html">Graphics</a>
<a href="images_en.html">Image files</a>

<a href="external_en.html">External applications</a>
<span class="heading">Advanced Topics</span>

<a href="remote_en.html">Browsing</a>

<a href="config_en.html">Configuring Crunchy</a>
<a href="faq_en.html">FAQ, bugs, etc.</a>
<a href="writing_en.html">Writing tutorials</a>

<a href="/functional_tests">Tests</a>
</div>
<div id="main">
<div class="notes">
<h4>Please note</h4>
<p>
While we strive to keep it up to date, this document is possibly not up to date with the latest
configuration options - whereas "config.help" is extracted directly from the
source code and, as such, should always reflect the options available.
</p></div>
<p>Crunchy has been designed to be highly configurable by the end user.  
To see the various configuration options, you can type in <code>crunchy.help</code> in the 
interpreter below - or in any interpreter or other Crunchy object that can be used
to execute some Python code.  However, to make it a bit easier to figure 
out the various options, we will <b><i>eventually</i></b> 
<small>(not done yet)</small> describe each of them in this document.</p>
<pre title="interpreter">
&gt;&gt;&gt; crunchy.help
</pre>
<h3 class="crunchy">Selecting the security level</h3>
<p>Before changing the security level, you should read the FAQ entry on this topic.</p>
<p>By default, the security level is set to <code>normal</code>.  You can select a
different security level as follows:
</p>
<pre title="interpreter">
&gt;&gt;&gt; # choose among 'strict', 'normal', 'trusted', 'display strict' ...
&gt;&gt;&gt; # ... 'display normal', 'display trusted'
&gt;&gt;&gt; crunchy.local_security = 'strict'
</pre>
<p>This will only affect the processing of pages that resides on your computer,
whether they are part of the Crunchy distribution or others loaded via the
file browser.</p>
<p>Remember that if you choose a security level that starts with <code>display</code>
no interactive elements will remain and, unless you have another previously open page
in a different tab or window, you will not be able to change that setting during
the current Crunchy session.</p>
<h3 class="crunchy">Selecting the language</h3>
<p>Crunchy has been designed to be translatable so feedback to the user could be
given in languages other than English.  However, as of version 0.9.2, no 
actual translation is available except for EditArea, the
embedded source code editor.  You can try the following examples to see the language
configuration in action.</p>
<p>Our plan is to make Crunchy's configuration more complete and friendlier by
the time version 1.0 is released.</p>
<pre title="editor">
# The following will raise an error message as of version 0.9.2
crunchy.language = 'fr'

# Note that if the chosen language is available, Crunchy tries
# to also set the same language for EditArea.

# The language used by EditArea can always be set using the following.
crunchy.editarea_language = 'fr'

# When the page is created, the default values are used.
# To see the effect of the new selection, you will need to reload
# the page after executing the code, toggle the editor, and hover
# your mouse over the various editor icons.
</pre>

<h3 class="crunchy">Changing the default interpreter</h3>
<p>The interpreter of choice for Crunchy is the "Borg" interpreter - this is the
interpreter chosen when <code>title = "interpreter"</code> is inserted inside a 
<code>pre</code> tag.  While a tutorial writer may specify any type of interpreter
to be inserted, a user can always overrule that choice - this can be particularly
useful for a teacher who might want to demonstrate certain aspects
of Python in a classroom situation.  Such an assignment is done as follows</p>
<pre title="interpreter">
&gt;&gt;&gt; crunchy.override_default_interpreter = "Borg"
</pre>
<p>If the user specifies "default", Crunchy will revert to following the
choices specified in the tutorial's vlam code.
</p>

<h3 class="crunchy">Friendly tracebacks</h3>
<p>Crunchy makes some attempts at providing tracebacks that are a bit friendlier
than those used by Python as a default.  In doing so, we make it possible to 
express at least some parts of the tracebacks in languages other than English -
if the translations are available. To see this in action, try the
following doctest example, making sure it will not run satisfactorily (perhaps
by simply pressing the "Run doctest" button.  As a second step, change the
tracebacks used as indicated below.</p>
<pre title="doctest">
&gt;&gt;&gt; double(22)
44
</pre>

<p>To change the tracebacks used, change the value of the "friendly" parameter from 
<code title="py_code">True</code> to <code title="py_code">False</code>.</p>
<pre title="interpreter">
&gt;&gt;&gt; crunchy.friendly = False
</pre>


<h3 class="crunchy">Styles (Note: everything below needs to be updated)</h3>
<p>One of Crunchy's main feature for tutorial writers is that it takes away
the drudgery of styling Python code by hand (or cutting and pasting code that was
styled by an external program); all that a tutorial writer has to do is
to type in the code inside a &lt;pre&gt; or &lt;code&gt; html element and
specify the Crunchy specific <code>title</code> attribute, and Crunchy
takes care of the rest.  However, the default styling done by Crunchy may
not be to the taste of everyone: this is why we give you some options
to change it.</p>
<p>Crunchy's styling goes through four steps:</p>
<ol>
<li>Crunchy applies its default.</li>
<li>A tutorial writer may over-ride Crunchy's default, either by explicit styling
in the html file, or by linking to an external style sheet.  
<a href="/functional_tests/css_override.html">Here's an example.</a></li>
<li>A user may override the tutorial writer's choice; some examples will be given below.
In order to do so, the user must set <code title="py_code">crunchy.my_style = True</code>
and then define a style as a Python dict stored in <code title="py_code">crunchy.styles</code></li>
<li>Finally, a tutorial writer may choose to instruct Crunchy not to add any styling
on any given element (usually a <code>pre</code>)
and use its own entirely.  In this case, a user would have to know the classes used
by the tutorial writer (perhaps through examining the source code) 
in order to instruct Crunchy to change the defaults.  We will not deal with this case here.</li>
</ol>
<p>Before we proceed with choices, here's a small code sample that you can use
to gauge the effect of any changes you might make.</p>
<pre title="py_code linenumber">
class Sample(object):
    '''A dummy class used to show the effect
    of different styling choices'''
    def __init__(self):
        '''the obligatory function'''
        self.name = 'Crunchy'   # a comment
    
    def hello(self):
        print "Hello world!"
        bit_of_math = 5 * 6 / 112
        return
</pre>

<h4 class="crunchy">Default Crunchy choice</h4>
<p>Here are the default choices made for Crunchy.  Note that we define a name for reference only
as it is not used for styling.</p>
<pre title="editor">
crunchy.styles = {
'name' : 'crunchy',
'.py_keyword': 'color: #336699; font-weight: bold;', 
'.py_number': 'color: #000000;', 
'.py_comment': 'color: gray;', 
'.py_string': 'color: #660066;', 
'.py_variable': 'color: #000000;', 
'.py_op': 'color: #993300; font-weight:bold;', 
'.py_builtins': 'color: #009900;', 
'.py_stdlib': 'color: #009900;', 
'.py_special': 'color: #006666;', 
'.py_linenumber': 'font-size: small; color: #666666;', 
'.py_prompt': 'color:blue;', 
'.py_output': 'color:blue;', 
'.py_warning': 'background-color:yellow; font-size: large; font-weight: bold;', 
'.py_pre': 'text-align: left;font-size:12pt;',
'.stdout': 'color: blue; font-weight: normal;',
'.stderr': 'color: red;',
'.input': 'width: 80%; max-width: 800px; font: 11pt monospace; font-weight: bold;'+\
    'border: solid 1px; border-width: 2px; background-color: #eff; border-color: #369;',
'.output': 'font: 11pt monospace; font-weight: bold; color:darkgreen;' ,
'button': 'background-color: #369; color: white;',
'button:hover': 'background-color: #369; border-bottom-color: #fe0; color:#fe0;'
}
crunchy.my_style = True
print "style set to", crunchy.styles['name']
</pre>

<h4 class="crunchy">Black on white</h4>
<p>Possibly the most boring styling choice that could be made: all text in black
on a white background.</p>
<pre title="editor">
crunchy.styles = {
'name' : 'black on white',
'.py_keyword': 'color: black; font-weight: bold;', 
'.py_number': 'color: black;', 
'.py_comment': 'color: black;', 
'.py_string': 'color: black;', 
'.py_variable': 'color: black;', 
'.py_op': 'color: black; font-weight:bold;', 
'.py_builtins': 'color: black;', 
'.py_stdlib': 'color: black;', 
'.py_special': 'color: black;', 
'.py_linenumber': 'font-size: small; color: black;', 
'.py_prompt': 'color:black;', 
'.py_output': 'color:black;', 
'.py_warning': 'background-color:white; font-size: large; font-weight: bold;', 
'.py_pre': 'text-align: left;font-size:12pt;',
'.stdout': 'color: black; font-weight: normal;',
'.stderr': 'color: black;',
'.input': 'width: 80%; max-width: 800px; font: 11pt monospace; font-weight:'+\
  'bold; border: solid 1px; border-width: 2px; background-color: white; border-color: black;',
'.output': 'font: 11pt monospace; font-weight: bold; color:black;',
'button': 'background-color: black; color: white;',
'button:hover': 'background-color: white; border-bottom-color: black; color:black;'
}
crunchy.my_style = True
print "style set to", crunchy.styles['name']
</pre>

<h4 class="crunchy">Colorful on dark</h4>
<p>Here's a most colorful theme on a dark background.</p>
<pre title="editor">
crunchy.styles = {
'name' : 'colorful on black',
'body': 'color:yellow; background-color: #000033;',
'pre': 'width:1000px; background-color: black;',
'.py_keyword': 'color: orange; font-weight: bold;', 
'.py_number': 'color: red;', 
'.py_comment': 'color: silver;', 
'.py_string': 'color: aqua;', 
'.py_variable': 'color: white;', 
'.py_op': 'color: blue; font-weight:bold;', 
'.py_builtins': 'color: steelblue;', 
'.py_stdlib': 'color: yellow;', 
'.py_special': 'color: pink;', 
'.py_linenumber': 'font-size: small; color: chocolate;', 
'.py_prompt': 'color:green;', 
'.py_output': 'color:magenta;', 
'.py_warning': 'background-color:black; font-size: large; font-weight: bold;', 
'.py_pre': 'text-align: left;font-size:12pt; background-color:black; width:900px;',
'.stdout': 'color: blueviolet; font-weight: normal;  background-color:black;',
'.stderr': 'color: orangered;  background-color:black;',
'.input': 'width: 80%; max-width: 800px; font: 11pt monospace; font-weight: bold; border: solid 1px;'+\
          'border-width: 2px; color: darkseagreen; background-color: black; border-color: yellow;',
'.output': 'font: 11pt monospace; font-weight: bold; color:springgreen; background-color:black;' ,
'button': 'background-color: yellow; color: black;',
'button:hover': 'background-color: black; border-bottom-color: yellow; color:white;',
# What follows is specific to Crunchy tutorials
'.wide-notes': ' border: 1px solid yellow; background-color:black; color:yellow;',
'.wide-notes h4': ' border-bottom: 3px solid yellow; background-color:yellow; color:black;',
'.notes': ' border: 1px solid yellow; background-color:black; color:yellow;',
'.notes h4': ' border-bottom: 3px solid yellow; background-color:yellow; color:black;',
'.wide-warning': ' border: 1px solid red; background-color:black; color:yellow;',
'.wide-warning h4': ' border-bottom: 3px solid red; background-color:red; color:black;',
'#navbar span.heading' : 'color: tan; background-color: black',
'#navbar a' : 'color: yellow; background-color: black',
'#navbar a:hover': 'background-color: yellow; color: black',
'table.summary': ' background-color:#F5F5DC; color: black;'
}
crunchy.my_style = True
print "style set to", crunchy.styles['name']
</pre>

</div>
</body>
</html>
